Case Definition

A case definition is the config-driven template for a type of case. It is a JSON document validated against the WKS Case Configuration Standard — the canonical schema published at packages/case-config-schema/schemas/case-definition.schema.json.

This page is the field-level reference for that document. Stages, event listeners (hooks) and queues each have their own page.

Fields

Field	Type	Required	Description
`id`	string	✅	Stable unique identifier for the case type (slug).
`name`	string	✅	Human-readable case type name.
`formKey`	string	✅	Key of the Form that renders this case type's data.
`stagesLifecycleProcessKey`	string		Key of the BPMN process driving the stage lifecycle. Empty/absent when running engine-less (`wks.bpm.engine=none`).
`deployed`	boolean		Whether the case type is available to end users.
`stages`	array		Ordered lifecycle stages.
`caseHooks`	array		Event-driven automation: event listeners.
`requiredDocuments`	array		Config-declared document discipline: the required documents a case of this type is expected to hold.
`schemaVersion`	string		Version of the WKS Case Configuration Standard this document conforms to. See Configuration Versioning.

Legacy / storage fields

Seed data may also contain bpmEngineId (a legacy field that is silently ignored by the engine) and _id (a storage envelope field, e.g. a MongoDB ObjectId wrapper). Neither is part of the logical configuration contract; do not rely on them.

Board rendering — moved out of the contract in 2.0

Earlier versions carried a kanbanConfig object on the case definition. As of Standard 2.0 it has been removed — it was a presentation concern, not part of the case-definition contract. The kanban board's columns are derived from stages, and per-card presentation now lives in its own artifact, board-config.schema.json, keyed by case definition id.

Example

A trimmed real case definition (the demo customer-support type):

{
  "id": "customer-support",
  "name": "Customer Support Case",
  "formKey": "customer-support-form",
  "stagesLifecycleProcessKey": "customer-support",
  "deployed": true,
  "schemaVersion": "2.0",
  "stages": [
    { "id": "0", "index": 0, "name": "Ticket Creation" },
    { "id": "1", "index": 1, "name": "Issue Investigation" },
    { "id": "2", "index": 2, "name": "Resolution" }
  ],
  "caseHooks": [
    {
      "eventType": "TASK_COMPLETE_EVENT_TYPE",
      "processDefKey": "customer-support",
      "taskDefKey": "create-ticket",
      "actions": [
        { "actionType": "CASE_STAGE_UPDATE_ACTION", "newStage": "Issue Investigation" }
      ]
    }
  ]
}

Authoring

Case definitions can be created and edited through the Case Builder (Management → Case Definitions) or by importing JSON directly. The Case Builder includes a JSON view that validates the definition against the Standard as you edit. See Creating Case Definitions.

Fields​

Example​

Authoring​

Fields

Example

Authoring